<!DOCTYPE html>
<html lang="en">
<head>
	<meta charset="UTF-8">
	<meta http-equiv="X-UA-Compatible" content="IE=edge">
    <meta name="viewport" content="width=device-width, initial-scale=1">
	<title>Create anomaly detection jobs API | ElasticSearch 7.7 权威指南中文版</title>
	<meta name="keywords" content="ElasticSearch 权威指南中文版, elasticsearch 7, es7, 实时数据分析，实时数据检索" />
    <meta name="description" content="ElasticSearch 权威指南中文版, elasticsearch 7, es7, 实时数据分析，实时数据检索" />
    <!-- Give IE8 a fighting chance -->
    <!--[if lt IE 9]>
    <script src="https://oss.maxcdn.com/html5shiv/3.7.2/html5shiv.min.js"></script>
    <script src="https://oss.maxcdn.com/respond/1.4.2/respond.min.js"></script>
    <![endif]-->
	<link rel="stylesheet" type="text/css" href="../static/styles.css" />
	<script>
	var _link = 'ml-put-job.html';
    </script>
</head>
<body>
<div class="main-container">
    <section id="content">
        <div class="content-wrapper">
            <section id="guide" lang="zh_cn">
                <div class="container">
                    <div class="row">
                        <div class="col-xs-12 col-sm-8 col-md-8 guide-section">
                            <div style="color:gray; word-break: break-all; font-size:12px;">原英文版地址: <a href="https://www.elastic.co/guide/en/elasticsearch/reference/7.7/ml-put-job.html" rel="nofollow" target="_blank">https://www.elastic.co/guide/en/elasticsearch/reference/7.7/ml-put-job.html</a>, 原文档版权归 www.elastic.co 所有<br/>本地英文版地址: <a href="../en/ml-put-job.html" rel="nofollow" target="_blank">../en/ml-put-job.html</a></div>
                        <!-- start body -->
                  <div class="page_header">
<strong>重要</strong>: 此版本不会发布额外的bug修复或文档更新。最新信息请参考 <a href="https://www.elastic.co/guide/en/elasticsearch/reference/current/index.html" rel="nofollow">当前版本文档</a>。
</div>
<div id="content">
<div class="breadcrumbs">
<span class="breadcrumb-link"><a href="index.html">Elasticsearch Guide [7.7]</a></span>
»
<span class="breadcrumb-link"><a href="rest-apis.html">REST APIs</a></span>
»
<span class="breadcrumb-link"><a href="ml-apis.html">Machine learning anomaly detection APIs</a></span>
»
<span class="breadcrumb-node">Create anomaly detection jobs API</span>
</div>
<div class="navheader">
<span class="prev">
<a href="ml-close-job.html">« Close anomaly detection jobs API</a>
</span>
<span class="next">
<a href="ml-put-calendar.html">Create calendar API »</a>
</span>
</div>
<div class="section xpack">
<div class="titlepage"><div><div>
<h2 class="title">
<a id="ml-put-job"></a>Create anomaly detection jobs API<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/docs/reference/ml/anomaly-detection/apis/put-job.asciidoc">edit</a><a class="xpack_tag" href="https://www.elastic.co/subscriptions"></a>
</h2>
</div></div></div>

<p>Instantiates an anomaly detection job.</p>
<div class="section">
<div class="titlepage"><div><div>
<h3 class="title">
<a id="ml-put-job-request"></a>Request<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/docs/reference/ml/anomaly-detection/apis/put-job.asciidoc">edit</a>
</h3>
</div></div></div>
<p><code class="literal">PUT _ml/anomaly_detectors/&lt;job_id&gt;</code></p>
</div>

<div class="section">
<div class="titlepage"><div><div>
<h3 class="title">
<a id="ml-put-job-prereqs"></a>Prerequisites<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/docs/reference/ml/anomaly-detection/apis/put-job.asciidoc">edit</a>
</h3>
</div></div></div>
<div class="ulist itemizedlist">
<ul class="itemizedlist">
<li class="listitem">
If the Elasticsearch security features are enabled, you must have <code class="literal">manage_ml</code> or
<code class="literal">manage</code> cluster privileges to use this API. See
<a class="xref" href="security-privileges.html" title="Security privileges">Security privileges</a>.
</li>
</ul>
</div>
</div>

<div class="section">
<div class="titlepage"><div><div>
<h3 class="title">
<a id="ml-put-job-desc"></a>Description<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/docs/reference/ml/anomaly-detection/apis/put-job.asciidoc">edit</a>
</h3>
</div></div></div>
<div class="important admon">
<div class="icon"></div>
<div class="admon_content">
<p>You must use Kibana or this API to create an anomaly detection job. Do not put
a job directly to the <code class="literal">.ml-config</code> index using the Elasticsearch index API. If Elasticsearch
security features are enabled, do not give users <code class="literal">write</code> privileges on the
<code class="literal">.ml-config</code> index.</p>
</div>
</div>
</div>

<div class="section">
<div class="titlepage"><div><div>
<h3 class="title">
<a id="ml-put-job-path-parms"></a>Path parameters<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/docs/reference/ml/anomaly-detection/apis/put-job.asciidoc">edit</a>
</h3>
</div></div></div>
<div class="variablelist">
<dl class="variablelist">
<dt>
<span class="term">
<code class="literal">&lt;job_id&gt;</code>
</span>
</dt>
<dd>
(Required, string)
Identifier for the anomaly detection job. This identifier can contain lowercase
alphanumeric characters (a-z and 0-9), hyphens, and underscores. It must start
and end with alphanumeric characters.
</dd>
</dl>
</div>
</div>

<div class="section child_attributes">
<div class="titlepage"><div><div>
<h3 class="title">
<a id="ml-put-job-request-body"></a>Request body<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/docs/reference/ml/anomaly-detection/apis/put-job.asciidoc">edit</a>
</h3>
</div></div></div>
<div class="variablelist">
<dl class="variablelist">
<dt>
<span class="term">
<code class="literal">allow_lazy_open</code>
</span>
</dt>
<dd>
(Optional, boolean)
Advanced configuration option. Specifies whether this job can open when there is
insufficient machine learning node capacity for it to be immediately assigned to a node. The
default value is <code class="literal">false</code>; if a machine learning node with capacity to run the job cannot
immediately be found, the <a class="xref" href="ml-open-job.html" title="Open anomaly detection jobs API">open anomaly detection jobs API</a> returns an
error. However, this is also subject to the cluster-wide
<code class="literal">xpack.ml.max_lazy_ml_nodes</code> setting; see <a class="xref" href="ml-settings.html#advanced-ml-settings" title="Advanced machine learning settings">Advanced machine learning settings</a>. If this
option is set to <code class="literal">true</code>, the <a class="xref" href="ml-open-job.html" title="Open anomaly detection jobs API">open anomaly detection jobs API</a> does not
return an error and the job waits in the <code class="literal">opening</code> state until sufficient machine learning
node capacity is available.
</dd>
</dl>
</div>
<div class="variablelist">
<dl class="variablelist">
<dt>
<span class="term">
<a id="put-analysisconfig"></a><code class="literal">analysis_config</code>
</span>
</dt>
<dd>
<p>
(Required, object)
The analysis configuration, which specifies how to analyze the data. After you
create a job, you cannot change the analysis configuration; all the properties
are informational.
</p>
<details open>
<summary class="title">Properties of <code class="literal">analysis_config</code></summary>
<div class="content">
<div class="variablelist">
<dl class="variablelist">
<dt>
<span class="term">
<code class="literal">bucket_span</code>
</span>
</dt>
<dd>
(<a class="xref" href="common-options.html#time-units" title="Time units">time units</a>)
The size of the interval that the analysis is aggregated into, typically between
<code class="literal">5m</code> and <code class="literal">1h</code>. The default value is <code class="literal">5m</code>. If the anomaly detection job uses a datafeed
with <a href="https://www.elastic.co/guide/en/machine-learning/7.7/ml-configuring-aggregation.html" class="ulink" target="_top">aggregations</a>, this value must be
divisible by the interval of the date histogram aggregation. For more
information, see <a href="https://www.elastic.co/guide/en/machine-learning/7.7/ml-buckets.html" class="ulink" target="_top">Buckets</a>.
</dd>
<dt>
<span class="term">
<code class="literal">categorization_analyzer</code>
</span>
</dt>
<dd>
<p>
(object or string)
If <code class="literal">categorization_field_name</code> is specified, you can also define the analyzer
that is used to interpret the categorization field. This property cannot be used
at the same time as <code class="literal">categorization_filters</code>. The categorization analyzer
specifies how the categorization field is interpreted by the categorization
process. The syntax is very similar to that used to define the <code class="literal">analyzer</code> in the
<a class="xref" href="indices-analyze.html" title="Analyze API">Analyze endpoint</a>. For more information, see
<a href="https://www.elastic.co/guide/en/machine-learning/7.7/ml-configuring-categories.html" class="ulink" target="_top">Categorizing log messages</a>.
</p>
<p>The <code class="literal">categorization_analyzer</code> field can be specified either as a string or as an
object. If it is a string it must refer to a
<a class="xref" href="analysis-analyzers.html" title="Built-in analyzer reference">built-in analyzer</a> or one added by another plugin. If it
is an object it has the following properties:</p>
<details open>
<summary class="title">Properties of <code class="literal">categorization_analyzer</code></summary>
<div class="content">
<div class="variablelist">
<dl class="variablelist">
<dt>
<span class="term">
<code class="literal">char_filter</code>
</span>
</dt>
<dd>
(array of strings or objects)
One or more <a class="xref" href="analysis-charfilters.html" title="Character filters reference">character filters</a>. In addition to the
built-in character filters, other plugins can provide more character filters.
This property is optional. If it is not specified, no character filters are
applied prior to categorization. If you are customizing some other aspect of the
analyzer and you need to achieve the equivalent of <code class="literal">categorization_filters</code>
(which are not permitted when some other aspect of the analyzer is customized),
add them here as
<a class="xref" href="analysis-pattern-replace-charfilter.html" title="Pattern Replace Char Filter">pattern replace character filters</a>.
</dd>
<dt>
<span class="term">
<code class="literal">tokenizer</code>
</span>
</dt>
<dd>
(string or object)
The name or definition of the <a class="xref" href="analysis-tokenizers.html" title="Tokenizer reference">tokenizer</a> to use after
character filters are applied. This property is compulsory if
<code class="literal">categorization_analyzer</code> is specified as an object. Machine learning provides a
tokenizer called <code class="literal">ml_classic</code> that tokenizes in the same way as the
non-customizable tokenizer in older versions of the product. If you want to use
that tokenizer but change the character or token filters, specify
<code class="literal">"tokenizer": "ml_classic"</code> in your <code class="literal">categorization_analyzer</code>.
</dd>
<dt>
<span class="term">
<code class="literal">filter</code>
</span>
</dt>
<dd>
(array of strings or objects)
One or more <a class="xref" href="analysis-tokenfilters.html" title="Token filter reference">token filters</a>. In addition to the built-in
token filters, other plugins can provide more token filters. This property is
optional. If it is not specified, no token filters are applied prior to
categorization.
</dd>
</dl>
</div>
</div>
</details>
</dd>
<dt>
<span class="term">
<code class="literal">categorization_field_name</code>
</span>
</dt>
<dd>
(string)
If this property is specified, the values of the specified field will be
categorized. The resulting categories must be used in a detector by setting
<code class="literal">by_field_name</code>, <code class="literal">over_field_name</code>, or <code class="literal">partition_field_name</code> to the keyword
<code class="literal">mlcategory</code>. For more information, see
<a href="https://www.elastic.co/guide/en/machine-learning/7.7/ml-configuring-categories.html" class="ulink" target="_top">Categorizing log messages</a>.
</dd>
<dt>
<span class="term">
<code class="literal">categorization_filters</code>
</span>
</dt>
<dd>
(array of strings)
If <code class="literal">categorization_field_name</code> is specified, you can also define optional
filters. This property expects an array of regular expressions. The expressions
are used to filter out matching sequences from the categorization field values.
You can use this functionality to fine tune the categorization by excluding
sequences from consideration when categories are defined. For example, you can
exclude SQL statements that appear in your log files. For more information, see
<a href="https://www.elastic.co/guide/en/machine-learning/7.7/ml-configuring-categories.html" class="ulink" target="_top">Categorizing log messages</a>. This
property cannot be used at the same time as <code class="literal">categorization_analyzer</code>. If you
only want to define simple regular expression filters that are applied prior to
tokenization, setting this property is the easiest method. If you also want to
customize the tokenizer or post-tokenization filtering, use the
<code class="literal">categorization_analyzer</code> property instead and include the filters as
<code class="literal">pattern_replace</code> character filters. The effect is exactly the same.
</dd>
</dl>
</div>
<div class="variablelist">
<dl class="variablelist">
<dt>
<span class="term">
<code class="literal">detectors</code>
</span>
</dt>
<dd>
<p>
(array) An array of detector configuration objects. Detector configuration
objects specify which data fields a job analyzes. They also specify which
analytical functions are used. You can specify multiple detectors for a job.
</p>
<div class="note admon">
<div class="icon"></div>
<div class="admon_content">
<p>If the <code class="literal">detectors</code> array does not contain at least one detector,
no analysis can occur and an error is returned.</p>
</div>
</div>
<details open>
<summary class="title">Properties of <code class="literal">detectors</code></summary>
<div class="content">
<div class="variablelist">
<dl class="variablelist">
<dt>
<span class="term">
<code class="literal">by_field_name</code>
</span>
</dt>
<dd>
(string)
The field used to split the data. In particular, this property is used for
analyzing the splits with respect to their own history. It is used for finding
unusual values in the context of the split.
</dd>
</dl>
</div>
<div class="variablelist">
<dl class="variablelist">
<dt>
<span class="term">
<a id="put-customrules"></a><code class="literal">custom_rules</code>
</span>
</dt>
<dd>
<p>
(array)
An array of custom rule objects, which enable you to customize the way detectors
operate. For example, a rule may dictate to the detector conditions under which
results should be skipped. For more examples, see
<a href="https://www.elastic.co/guide/en/machine-learning/7.7/ml-configuring-detector-custom-rules.html" class="ulink" target="_top">Customizing detectors with custom rules</a>.
</p>
<details open>
<summary class="title">Properties of <code class="literal">custom_rules</code></summary>
<div class="content">
<div class="variablelist">
<dl class="variablelist">
<dt>
<span class="term">
<code class="literal">actions</code>
</span>
</dt>
<dd>
<p>
(array)
The set of actions to be triggered when the rule applies. If
more than one action is specified the effects of all actions are combined. The
available actions include:
</p>
<div class="ulist itemizedlist">
<ul class="itemizedlist">
<li class="listitem">
<code class="literal">skip_result</code>: The result will not be created. This is the default value.
Unless you also specify <code class="literal">skip_model_update</code>, the model will be updated as usual
with the corresponding series value.
</li>
<li class="listitem">
<code class="literal">skip_model_update</code>: The value for that series will not be used to update the
model. Unless you also specify <code class="literal">skip_result</code>, the results will be created as
usual. This action is suitable when certain values are expected to be
consistently anomalous and they affect the model in a way that negatively
impacts the rest of the results.
</li>
</ul>
</div>
</dd>
</dl>
</div>
<div class="variablelist">
<dl class="variablelist">
<dt>
<span class="term">
<code class="literal">conditions</code>
</span>
</dt>
<dd>
<p>
(array)
An optional array of numeric conditions when the rule applies. A rule must
either have a non-empty scope or at least one condition. Multiple conditions are
combined together with a logical <code class="literal">AND</code>. A condition has the following
properties:
</p>
<details open>
<summary class="title">Properties of <code class="literal">conditions</code></summary>
<div class="content">
<div class="variablelist">
<dl class="variablelist">
<dt>
<span class="term">
<code class="literal">applies_to</code>
</span>
</dt>
<dd>
(string)
Specifies the result property to which the condition applies. The available
options are <code class="literal">actual</code>, <code class="literal">typical</code>, <code class="literal">diff_from_typical</code>, <code class="literal">time</code>. If your detector
uses <code class="literal">lat_long</code>, <code class="literal">metric</code>, <code class="literal">rare</code>, or <code class="literal">freq_rare</code> functions, you can only
specify conditions that apply to <code class="literal">time</code>.
</dd>
<dt>
<span class="term">
<code class="literal">operator</code>
</span>
</dt>
<dd>
(string)
Specifies the condition operator. The available options are <code class="literal">gt</code> (greater than),
<code class="literal">gte</code> (greater than or equals), <code class="literal">lt</code> (less than) and <code class="literal">lte</code> (less than or
equals).
</dd>
<dt>
<span class="term">
<code class="literal">value</code>
</span>
</dt>
<dd>
(double)
The value that is compared against the <code class="literal">applies_to</code> field using the <code class="literal">operator</code>.
</dd>
</dl>
</div>
</div>
</details>
</dd>
</dl>
</div>
<div class="variablelist">
<dl class="variablelist">
<dt>
<span class="term">
<code class="literal">scope</code>
</span>
</dt>
<dd>
<p>
(object)
An optional scope of series where the rule applies. A rule must either
have a non-empty scope or at least one condition. By default, the scope includes
all series. Scoping is allowed for any of the fields that are also specified in
<code class="literal">by_field_name</code>, <code class="literal">over_field_name</code>, or <code class="literal">partition_field_name</code>. To add a scope
for a field, add the field name as a key in the scope object and set its value
to an object with the following properties:
</p>
<details open>
<summary class="title">Properties of <code class="literal">scope</code></summary>
<div class="content">
<div class="variablelist">
<dl class="variablelist">
<dt>
<span class="term">
<code class="literal">filter_id</code>
</span>
</dt>
<dd>
(string)
The id of the filter to be used.
</dd>
<dt>
<span class="term">
<code class="literal">filter_type</code>
</span>
</dt>
<dd>
(string)
Either <code class="literal">include</code> (the rule applies for values in the filter) or <code class="literal">exclude</code> (the
rule applies for values not in the filter). Defaults to <code class="literal">include</code>.
</dd>
</dl>
</div>
</div>
</details>
</dd>
</dl>
</div>
</div>
</details>
</dd>
<dt>
<span class="term">
<code class="literal">detector_description</code>
</span>
</dt>
<dd>
(string)
A description of the detector. For example, <code class="literal">Low event rate</code>.
</dd>
<dt>
<span class="term">
<code class="literal">detector_index</code>
</span>
</dt>
<dd>
<p>
(integer)
A unique identifier for the detector. This identifier is based on the order of
the detectors in the <code class="literal">analysis_config</code>, starting at zero.
</p>
<p>If you specify a value for this property, it is ignored.</p>
</dd>
<dt>
<span class="term">
<code class="literal">exclude_frequent</code>
</span>
</dt>
<dd>
(string)
Contains one of the following values: <code class="literal">all</code>, <code class="literal">none</code>, <code class="literal">by</code>, or <code class="literal">over</code>. If set,
frequent entities are excluded from influencing the anomaly results. Entities
can be considered frequent over time or frequent in a population. If you are
working with both over and by fields, then you can set <code class="literal">exclude_frequent</code> to
<code class="literal">all</code> for both fields, or to <code class="literal">by</code> or <code class="literal">over</code> for those specific fields.
</dd>
<dt>
<span class="term">
<code class="literal">field_name</code>
</span>
</dt>
<dd>
<p>
(string)
The field that the detector uses in the function. If you use an event rate
function such as <code class="literal">count</code> or <code class="literal">rare</code>, do not specify this field.
</p>
<div class="note admon">
<div class="icon"></div>
<div class="admon_content">
<p>The <code class="literal">field_name</code> cannot contain double quotes or backslashes.</p>
</div>
</div>
</dd>
<dt>
<span class="term">
<code class="literal">function</code>
</span>
</dt>
<dd>
(string)
The analysis function that is used. For example, <code class="literal">count</code>, <code class="literal">rare</code>, <code class="literal">mean</code>, <code class="literal">min</code>,
<code class="literal">max</code>, and <code class="literal">sum</code>. For more information, see
<a href="https://www.elastic.co/guide/en/machine-learning/7.7/ml-functions.html" class="ulink" target="_top">Function reference</a>.
</dd>
<dt>
<span class="term">
<code class="literal">over_field_name</code>
</span>
</dt>
<dd>
(string)
The field used to split the data. In particular, this property is used for
analyzing the splits with respect to the history of all splits. It is used for
finding unusual values in the population of all splits. For more information,
see <a href="https://www.elastic.co/guide/en/machine-learning/7.7/ml-configuring-pop.html" class="ulink" target="_top">Performing population analysis</a>.
</dd>
<dt>
<span class="term">
<code class="literal">partition_field_name</code>
</span>
</dt>
<dd>
(string)
The field used to segment the analysis. When you use this property, you have
completely independent baselines for each value of this field.
</dd>
<dt>
<span class="term">
<code class="literal">use_null</code>
</span>
</dt>
<dd>
(boolean)
Defines whether a new series is used as the null series when there is no value
for the by or partition fields. The default value is <code class="literal">false</code>.
</dd>
</dl>
</div>
</div>
</details>
</dd>
<dt>
<span class="term">
<code class="literal">influencers</code>
</span>
</dt>
<dd>
(array of strings)
A comma separated list of influencer field names. Typically these can be the by,
over, or partition fields that are used in the detector configuration. You might
also want to use a field name that is not specifically named in a detector, but
is available as part of the input data. When you use multiple detectors, the use
of influencers is recommended as it aggregates results for each influencer
entity.
</dd>
<dt>
<span class="term">
<code class="literal">latency</code>
</span>
</dt>
<dd>
<p>
(<a class="xref" href="common-options.html#time-units" title="Time units">time units</a>)
The size of the window in which to expect data that is out of time order. The
default value is 0 (no latency). If you specify a non-zero value, it must be
greater than or equal to one second. For more information about time units, see
<a class="xref" href="common-options.html#time-units" title="Time units">Time units</a>.
</p>
<div class="note admon">
<div class="icon"></div>
<div class="admon_content">
<p>Latency is only applicable when you send data by using
the <a class="xref" href="ml-post-data.html" title="Post data to jobs API">post data</a> API.</p>
</div>
</div>
</dd>
<dt>
<span class="term">
<code class="literal">multivariate_by_fields</code>
</span>
</dt>
<dd>
<p>
(boolean)
This functionality is reserved for internal use. It is not supported for use in
customer environments and is not subject to the support SLA of official GA
features.
</p>
<p>If set to <code class="literal">true</code>, the analysis will automatically find correlations between
metrics for a given <code class="literal">by</code> field value and report anomalies when those
correlations cease to hold. For example, suppose CPU and memory usage on host A
is usually highly correlated with the same metrics on host B. Perhaps this
correlation occurs because they are running a load-balanced application.
If you enable this property, then anomalies will be reported when, for example,
CPU usage on host A is high and the value of CPU usage on host B is low. That
is to say, you’ll see an anomaly when the CPU of host A is unusual given
the CPU of host B.</p>
<div class="note admon">
<div class="icon"></div>
<div class="admon_content">
<p>To use the <code class="literal">multivariate_by_fields</code> property, you must also specify
<code class="literal">by_field_name</code> in your detector.</p>
</div>
</div>
</dd>
<dt>
<span class="term">
<code class="literal">summary_count_field_name</code>
</span>
</dt>
<dd>
<p>
(string)
If this property is specified, the data that is fed to the job is expected to be
pre-summarized. This property value is the name of the field that contains the
count of raw data points that have been summarized. The same
<code class="literal">summary_count_field_name</code> applies to all detectors in the job.
</p>
<div class="note admon">
<div class="icon"></div>
<div class="admon_content">
<p>The <code class="literal">summary_count_field_name</code> property cannot be used with the <code class="literal">metric</code>
function.</p>
</div>
</div>
</dd>
</dl>
</div>
</div>
</details>
</dd>
</dl>
</div>
<div class="variablelist">
<dl class="variablelist">
<dt>
<span class="term">
<a id="put-analysislimits"></a><code class="literal">analysis_limits</code>
</span>
</dt>
<dd>
<p>
(Optional, object)
Limits can be applied for the resources required to hold the mathematical models
in memory. These limits are approximate and can be set per job. They do not
control the memory used by other processes, for example the Elasticsearch Java processes.
</p>
<details open>
<summary class="title">Properties of <code class="literal">analysis_limits</code></summary>
<div class="content">
<div class="variablelist">
<dl class="variablelist">
<dt>
<span class="term">
<code class="literal">categorization_examples_limit</code>
</span>
</dt>
<dd>
<p>
(long)
The maximum number of examples stored per category in memory and in the results
data store. The default value is <code class="literal">4</code>.  If you increase this value, more examples
are available, however it requires that you have more storage available. If you
set this value to <code class="literal">0</code>, no examples are stored.
</p>
<div class="note admon">
<div class="icon"></div>
<div class="admon_content">
<p>The <code class="literal">categorization_examples_limit</code> only applies to analysis that uses
categorization. For more information, see
<a href="https://www.elastic.co/guide/en/machine-learning/7.7/ml-configuring-categories.html" class="ulink" target="_top">Categorizing log messages</a>.</p>
</div>
</div>
</dd>
<dt>
<span class="term">
<code class="literal">model_memory_limit</code>
</span>
</dt>
<dd>
<p>
(long or string)
The approximate maximum amount of memory resources that are required for
analytical processing. Once this limit is approached, data pruning becomes
more aggressive. Upon exceeding this limit, new entities are not modeled. The
default value for jobs created in version 6.1 and later is <code class="literal">1024mb</code>.
This value will need to be increased for jobs that are expected to analyze high
cardinality fields, but the default is set to a relatively small size to ensure
that high resource usage is a conscious decision. The default value for jobs
created in versions earlier than 6.1 is <code class="literal">4096mb</code>.
</p>
<p>If you specify a number instead of a string, the units are assumed to be MiB.
Specifying a string is recommended for clarity. If you specify a byte size unit
of <code class="literal">b</code> or <code class="literal">kb</code> and the number does not equate to a discrete number of megabytes,
it is rounded down to the closest MiB. The minimum valid value is 1 MiB. If you
specify a value less than 1 MiB, an error occurs. For more information about
supported byte size units, see <a class="xref" href="common-options.html#byte-units" title="Byte size units">Byte size units</a>.</p>
<p>If your <code class="literal">elasticsearch.yml</code> file contains an <code class="literal">xpack.ml.max_model_memory_limit</code>
setting, an error occurs when you try to create jobs that have
<code class="literal">model_memory_limit</code> values greater than that setting. For more information,
see <a class="xref" href="ml-settings.html" title="Machine learning settings in Elasticsearch">Machine learning settings</a>.</p>
</dd>
</dl>
</div>
</div>
</details>
</dd>
<dt>
<span class="term">
<code class="literal">background_persist_interval</code>
</span>
</dt>
<dd>
<p>
(Optional, <a class="xref" href="common-options.html#time-units" title="Time units">time units</a>)
Advanced configuration option. The time between each periodic persistence of the
model. The default value is a randomized value between 3 to 4 hours, which
avoids all jobs persisting at exactly the same time. The smallest allowed value
is 1 hour.
</p>
<div class="tip admon">
<div class="icon"></div>
<div class="admon_content">
<p>For very large models (several GB), persistence could take 10-20 minutes,
so do not set the <code class="literal">background_persist_interval</code> value too low.</p>
</div>
</div>
</dd>
<dt>
<span class="term">
<a id="put-customsettings"></a><code class="literal">custom_settings</code>
</span>
</dt>
<dd>
(Optional, object)
Advanced configuration option. Contains custom meta data about the job. For
example, it can contain custom URL information as shown in
<a href="https://www.elastic.co/guide/en/machine-learning/7.7/ml-configuring-url.html" class="ulink" target="_top">Adding custom URLs to machine learning results</a>.
</dd>
</dl>
</div>
<div class="variablelist">
<dl class="variablelist">
<dt>
<span class="term">
<a id="put-datadescription"></a><code class="literal">data_description</code>
</span>
</dt>
<dd>
<p>
(Required, object)
The data description defines the format of the input data when you send data to
the job by using the <a class="xref" href="ml-post-data.html" title="Post data to jobs API">post data</a> API. Note that when configure
a datafeed, these properties are automatically set. When data is received via
the <a class="xref" href="ml-post-data.html" title="Post data to jobs API">post data</a> API, it is not stored in Elasticsearch. Only the results
for anomaly detection are retained.
</p>
<details open>
<summary class="title">Properties of <code class="literal">data_description</code></summary>
<div class="content">
<div class="variablelist">
<dl class="variablelist">
<dt>
<span class="term">
<code class="literal">format</code>
</span>
</dt>
<dd>
(string) Only <code class="literal">JSON</code> format is supported at this time.
</dd>
<dt>
<span class="term">
<code class="literal">time_field</code>
</span>
</dt>
<dd>
(string) The name of the field that contains the timestamp.
The default value is <code class="literal">time</code>.
</dd>
<dt>
<span class="term">
<code class="literal">time_format</code>
</span>
</dt>
<dd>
<p>
(string)
The time format, which can be <code class="literal">epoch</code>, <code class="literal">epoch_ms</code>, or a custom pattern. The
default value is <code class="literal">epoch</code>, which refers to UNIX or Epoch time (the number of
seconds since 1 Jan 1970). The value <code class="literal">epoch_ms</code> indicates that time is measured
in milliseconds since the epoch. The <code class="literal">epoch</code> and <code class="literal">epoch_ms</code> time formats accept
either integer or real values.<br>
</p>
<div class="note admon">
<div class="icon"></div>
<div class="admon_content">
<p>Custom patterns must conform to the Java <code class="literal">DateTimeFormatter</code> class.
When you use date-time formatting patterns, it is recommended that you provide
the full date, time and time zone. For example: <code class="literal">yyyy-MM-dd'T'HH:mm:ssX</code>.
If the pattern that you specify is not sufficient to produce a complete
timestamp, job creation fails.</p>
</div>
</div>
</dd>
</dl>
</div>
</div>
</details>
</dd>
</dl>
</div>
<div class="variablelist">
<dl class="variablelist">
<dt>
<span class="term">
<code class="literal">description</code>
</span>
</dt>
<dd>
(Optional, string) A description of the job.
</dd>
<dt>
<span class="term">
<code class="literal">groups</code>
</span>
</dt>
<dd>
(Optional, array of strings)
A list of job groups. A job can belong to no groups or many.
</dd>
</dl>
</div>
<div class="variablelist">
<dl class="variablelist">
<dt>
<span class="term">
<code class="literal">model_plot_config</code>
</span>
</dt>
<dd>
<p>
(Optional, object)
This advanced configuration option stores model information along with the
results. It provides a more detailed view into anomaly detection.
</p>
<div class="warning admon">
<div class="icon"></div>
<div class="admon_content">
<p>If you enable model plot it can add considerable overhead to the
performance of the system; it is not feasible for jobs with many entities.</p>
</div>
</div>
<p>Model plot provides a simplified and indicative view of the model and its
bounds. It does not display complex features such as multivariate correlations
or multimodal data. As such, anomalies may occasionally be reported which cannot
be seen in the model plot.</p>
<p>Model plot config can be configured when the job is created or updated later. It
must be disabled if performance issues are experienced.</p>
<details open>
<summary class="title">Properties of <code class="literal">model_plot_config</code></summary>
<div class="content">
<div class="variablelist">
<dl class="variablelist">
<dt>
<span class="term">
<code class="literal">enabled</code>
</span>
</dt>
<dd>
(boolean)
If true, enables calculation and storage of the model bounds for each entity
that is being analyzed. By default, this is not enabled.
</dd>
<dt>
<span class="term">
<code class="literal">terms</code>
</span>
</dt>
<dd>
<span class="Admonishment Admonishment--experimental">
[<span class="Admonishment-title u-mono">experimental</span>]
<span class="Admonishment-detail">
This functionality is experimental and may be changed or removed completely in a future release. Elastic will take a best effort approach to fix any issues, but experimental features are not subject to the support SLA of official GA features.
</span>
</span> (string)
Limits data collection to this comma separated list of partition or by field
values. If terms are not specified or it is an empty string, no filtering is
applied. For example, "CPU,NetworkIn,DiskWrites". Wildcards are not supported.
Only the specified <code class="literal">terms</code> can be viewed when using the Single Metric Viewer.
</dd>
</dl>
</div>
</div>
</details>
</dd>
<dt>
<span class="term">
<code class="literal">model_snapshot_retention_days</code>
</span>
</dt>
<dd>
(Optional, long)
Advanced configuration option. The period of time (in days) that model snapshots
are retained. Age is calculated relative to the timestamp of the newest model
snapshot. The default value is <code class="literal">1</code>, which means snapshots that are one day
(twenty-four hours) older than the newest snapshot are deleted.
</dd>
<dt>
<span class="term">
<code class="literal">renormalization_window_days</code>
</span>
</dt>
<dd>
(Optional, long)
Advanced configuration option. The period over which adjustments to the score
are applied, as new data is seen. The default value is the longer of 30 days or
100 <code class="literal">bucket_spans</code>.
</dd>
<dt>
<span class="term">
<code class="literal">results_index_name</code>
</span>
</dt>
<dd>
(Optional, string)
A text string that affects the name of the machine learning results index. The default value
is <code class="literal">shared</code>, which generates an index named <code class="literal">.ml-anomalies-shared</code>.
</dd>
<dt>
<span class="term">
<code class="literal">results_retention_days</code>
</span>
</dt>
<dd>
(Optional, long)
Advanced configuration option. The period of time (in days) that results are
retained. Age is calculated relative to the timestamp of the latest bucket
result. If this property has a non-null value, once per day at 00:30 (server
time), results that are the specified number of days older than the latest
bucket result are deleted from Elasticsearch. The default value is null, which means all
results are retained.
</dd>
</dl>
</div>
</div>

<div class="section">
<div class="titlepage"><div><div>
<h3 class="title">
<a id="ml-put-job-example"></a>Examples<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/docs/reference/ml/anomaly-detection/apis/put-job.asciidoc">edit</a>
</h3>
</div></div></div>
<div class="pre_wrapper lang-console">
<pre class="programlisting prettyprint lang-console">PUT _ml/anomaly_detectors/total-requests
{
  "description" : "Total sum of requests",
  "analysis_config" : {
    "bucket_span":"10m",
    "detectors": [
      {
        "detector_description": "Sum of total",
        "function": "sum",
        "field_name": "total"
      }
    ]
  },
  "data_description" : {
    "time_field":"timestamp",
    "time_format": "epoch_ms"
  }
}</pre>
</div>
<div class="console_widget" data-snippet="snippets/1799.console"></div>
<p>When the job is created, you receive the following results:</p>
<div class="pre_wrapper lang-console-result">
<pre class="programlisting prettyprint lang-console-result">{
  "job_id" : "total-requests",
  "job_type" : "anomaly_detector",
  "job_version" : "7.5.0",
  "description" : "Total sum of requests",
  "create_time" : 1562352500629,
  "analysis_config" : {
    "bucket_span" : "10m",
    "detectors" : [
      {
        "detector_description" : "Sum of total",
        "function" : "sum",
        "field_name" : "total",
        "detector_index" : 0
      }
    ],
    "influencers" : [ ]
  },
  "analysis_limits" : {
    "model_memory_limit" : "1024mb",
    "categorization_examples_limit" : 4
  },
  "data_description" : {
    "time_field" : "timestamp",
    "time_format" : "epoch_ms"
  },
  "model_snapshot_retention_days" : 1,
  "results_index_name" : "shared",
  "allow_lazy_open" : false
}</pre>
</div>
</div>

</div>
<div class="navfooter">
<span class="prev">
<a href="ml-close-job.html">« Close anomaly detection jobs API</a>
</span>
<span class="next">
<a href="ml-put-calendar.html">Create calendar API »</a>
</span>
</div>
</div>

                  <!-- end body -->
                        </div>
                        <div class="col-xs-12 col-sm-4 col-md-4" id="right_col">
                        
                        </div>
                    </div>
                </div>
            </section>
        </div>
    </section>
</div>
<script src="../static/cn.js"></script>
</body>
</html>